home *** CD-ROM | disk | FTP | other *** search
- -------------------------------------------------------------------------------
-
-
- /¯¯¯¯¯) /¯) /¯¯¯¯¯) /¯¯¯¯¯)
- / /¯) / / / / ____/ / /¯) /
- / (_/ / / / / / / (_/ /
- / ____/ /¯¯¯¯) /¯¯¯¯¯) / / /¯¯¯¯¯) /¯¯¯¯¯) /¯¯¯) / ¯¯¯) / /
- / / / /¯¯¯ / /¯) / / / / /¯) / / /¯) / (___/ / /¯) / / /¯) /
- / / / / / (_/ / / / / (_/ / / (_/ / / (_/ / / (_/ /
- (_/ (_/ (_____/ (_/ (_____/ (___ / (_____/ (_____/
- / /
- /¯¯¯¯ /
- (_____/
-
- (pre-release version)
-
-
-
- © Copyright 1989-1994 Jens Kilian
- All rights reserved
-
-
- ------- Shipping list ---------------------------------------------------------
-
- CODES Pre-compiled versions of the compiler
- BUILTINS.WAM and run-time system
- DEBUGGER.WAM
- DRIVER.WAM
- DSTRUCT.WAM
- ENCODER.WAM
- INDEXER.WAM
- LIBRARY.WAM
- SHELL.WAM
- TMPALLOC.WAM
- XLATOR.WAM
-
- DOC
- LIESMICH This document (German version)
- README This document (English version)
-
- INIT.WAM Bootstrap information
- PROLOG.LST
-
- WAM.TOS Main program (emulator, primitive operations)
- MWAM.TOS Main program, MiNT library (untested!)
-
- ------- Overview --------------------------------------------------------------
-
- This package contains pre-release version 0.94.17 of Prolog-68, a not entirely
- new :-) Prolog system for Atari's ST series. When the program is finished, it
- will be made publicly available as free software (NOT public domain software!)
- together with the source code. This will take some time yet.
-
- The present version may be freely distributed, but NOT modified or used
- commercially. 'Commercial use' includes distribution, if a fee is charged
- and if the rate for a single disk exceeds the sum of the disk's price and
- the postal (or other carrier's) charge by more than DM 2,- (at a reasonable
- rate of exchange, if applicable).
-
- Again: This is a pre-release version, meaning that I don't even guarantee
- the correctness of this document!
-
- Prolog-68 is based on the `Warren Abstract Machine'; it contains a compiler
- (written in Prolog) which translates program clauses into intermediate code.
- This intermediate code is stored (as direct threaded code) and executed by a
- simulator. The system attains a speed of 12 kLIPS on the 'nrev' Benchmark,
- which is quite acceptable on an Atari ST. The program was tested on an ST
- with 4MB of main storage, but should be able to run on all Atari computers with
- 680x0 processors. In case of problems with TTs, Falcons or accelerated STs,
- please supply accurate error reports; I can't make tests myself because I don't
- have access to that kind of hardware. As usual, `more is better' regarding
- main memory; at least 250 KB are required just to load the system. The files
- in the 'CODES' folder contain a pre-translated version of the compiler and user
- interface. DON'T MODIFY THESE FILES UNDER ANY CIRCUMSTANCES, OTHERWISE YOU
- WON'T BE ABLE TO START PROLOG-68!
-
- ------- Incompatibilities to previous versions --------------------------------
-
- Version 0.9 to version 0.91:
-
- - On the Prolog level all characters are represented according to the Unicode
- standard (ISO DIS 10646-1.2 Basic Multilingual Plane). Previous versions
- used extended ASCII according to ISO 8859-1 resp. (still earlier) the Atari
- character set.
- The most important difference is in the representation of line endings in
- text files. All line endings read in are represented by the Prolog character
- code 16'2028 (ASCII NL = 16'0a is treated as equivalent on output). Programs
- that use is_endline/1 or is_newline/1 to test for line endings should
- encounter no difficulties; the same holds for using the "\n" escape sequence.
-
- (I will remove this special case in the next version because it gave me more
- problems than benefits. Sorry.)
-
- - According to the upcoming ISO standard, a 'cut' in the precondition of a call
- to '->'/2 has no effect on the rest of the clause.
-
- - The predicates constant/1 and nonconstant/1 have disappeared (replace them by
- atomic/1 resp. nonatomic/1). You don't want to know about this.
-
- Version 0.91 to version 0.93:
-
- - Line endings are represented by ASCII newlines again, for the reasons
- mentioned above.
-
- - The stream opening modes 'read_binary', 'write_binary' and 'append_binary'
- are no longer valid, since their purpose is served by the 'stream options'
- concept from the ISO standard.
-
- - It is no longer possible to list or trace compiled predicates. Access to
- single clauses is only possible for interpreted (dynamic) predicates. It is
- however still possible to set 'spy points' on compiled predicates in the
- debugger.
-
- - The debugger can now be explicitly switched on and off. It is no longer
- necessary to indicate the predicate to be debugged. The predicates debug/1
- and trace/1 don't exist any more.
-
- Version 0.93 to version 0.94:
-
- - absolute_file_name/2 may have different results because it now supports '/'
- as a directory separator (e.g., when running MiNT).
-
- ------- Known bugs ------------------------------------------------------------
-
- The present version 0.94.17 contains the following bugs (to be fixed in later
- versions):
-
- * NUL characters (ASCII 0) are not allowed in atoms' names.
-
- * Some database operations may not have correct update semantics.
- (I.e., a change may be visible to calls that were started before
- the change occurred.)
-
- ------- Invocation ------------------------------------------------------------
-
- The following are legal command-line options:
-
- -help Prints a short description of all the options.
-
- -debug Switches on an internal debugging mode. As it stands,
- this will be of use to the author only.
-
- -dribble <file> Opens a file into which all characters read from the
- keyboard will be echoed (useful for reporting bugs).
-
- -code <size> Allocates memory to the code area; this holds all
- long-lived data structures (such as atoms, functors and
- clauses).
-
- -global <size> Allocates memory to the global area, holding all terms
- created during program execution.
-
- -local <size> Allocates memory to the local area (used to control
- program execution and to hold local variables).
-
- -reserve <size> Returns memory to the operating system.
-
- Prolog-68 stores all data in three big areas of memory. Their sizes are
- computed at start-up and never changed afterwards. This restriction may
- cause a Prolog program to abort for lack of memory, even though enough
- free memory is present (future versions will include a mechanism for
- redistributing free memory at run-time). On computers having little main
- memory, it is thus important to set reasonable sizes for the different
- areas.
- If no options are given to it, Prolog-68 uses a very coarse partitioning
- which works well only with large amounts of memory. On STs with only 1MB
- of RAM, at least the code area should be explicitly set to about 250-300 KB.
- If memory is even smaller, 150 KB will be the absolute minimum.
-
- To distribute available memory to the various areas, the options '-code',
- '-global', '-local' and '-reserve' can be used. These may occur in any
- order and may be repeated (in which case their values will accumulate).
-
- Each of these four options must be followded by an additional argument
- giving the amount of memory to allocate. This should be a decimal integer
- optionally followed by one of the characters 'k', 'K', 'm', 'M' or '%'.
- If one of the letters is given or the flag character is omitted, the
- indicated number of bytes (resp. KBytes or MBytes) is allocated; if '%' is
- given, the indicated percentage of not-yet-allocated memory is used.
- Contiguous percentages refer to the same total amount.
-
- If the command line doesn't include sizes for one or more of the three
- areas, the total amount of memory which remains free after parsing of the
- command line is distributed to the missing areas, using a ratio of 1:2:4 for
- the code, local and global area, respectively. As mentioned above, this
- partitioning is not suitable for small-memory systems; for these, at least
- the code area has to be enlarged.
-
- If some memory remains free after the partitioning, it will be returned to
- the operating system. This is especially important if other programs must
- be run (either started from Prolog-68, or in a multi-tasking environment
- like MiNT). The '-reserve' option can be used to explicitly return a given
- amount of memory; it must be followed by an argument in the format given
- above.
-
- The following examples assume that exactly 2 MByte of main memory are free
- at start-up:
-
- -code 1M -global 50% -local 25%
- 1 MByte is assigned to the code area. Of the remaining memory,
- half (512 KByte) is given to the global area, a quarter (256 KByte)
- to the local area. The remaining 256 KByte are returned to the
- operating system.
-
- -code 25% -local 512K -code 25%
- A quarter of the initial 2 MByte is assigned to the code area.
- Another 512 KByte go to the local area. Of the remaining 1 MByte,
- another quarter is given to the code area. The rest is assigned to
- the global area, since it has not been given a size.
-
- No options given (default)
- 1/7 of total memory is assigned to the code area, 2/7 to the local
- area. The remaining 4/7 go to the global area. No memory is
- returned to the operating system.
-
- ------- Predefined predicates -------------------------------------------------
-
- I'm trying to create a complete Prolog system which is compatible to the
- upcoming ISO standard. The current version was inspired mostly by Edinburgh
- Prolog and dialects derived from it, so many details are likely to change.
- Most predefined predicates have already been implemented, but here they can
- only be described in short:
-
- - Control:
-
- ','/2 (the usual control constructs)
- ';'/2
- '!'/2
- '->'/2
- call/1
- '\+'/1 (non-provability, not a true negation)
- once/1
- true/0
- otherwise/0 (= true/0)
- fail/0
- false/0 (= fail/0)
- repeat/0
- if_exception/3 (error handling)
- signal_exception/1
- signal_error/3
- propagate_error/4
- trap/2
- set_error_handler/3
-
- The 'cut' works inside metacalls, but its scope is limited. In
- 'call(X)', a 'cut' inside 'X' will have effect only inside the
- parentheses. A rule of thumb: `letters block the cut'.
-
- '->'/2 resembles a 'cut' which is restricted to part of a clause.
- The call (P -> Q; R) can be used as an IF/THEN/ELSE statement:
- If P can be satisfied, Q is called, otherwise R is called.
- (P -> Q) on its own is identical to (P -> Q; fail).
- The ISO standard requires a 'cut' within the precondition (P in the
- example) not to have an effect on the rest of the clause. Thus, the
- above rule does NOT apply here!
-
- if_exception/3 and signal_exception/1 will be replaced by their ISO
- equivalents (catch/3 and throw/1) in a future version.
- The predicates signal_error/3, propagate_error/4, trap/2 and
- set_error_handler/3 will by replaced by an ISO compatible error
- handling mechanism.
-
- - Input/Output:
-
- read/1 (input/output of terms)
- write/1
- writeq/1
- display/1 (always outputs to 'user'!)
- write_canonical/1 (output in prefix form, also called displayq/1)
- print/1 (output via portray/1, if defined by the user)
- portray_clause/1 (prints clauses in easy-to-read format)
-
- get0/1 (input/output of characters)
- get/1
- skip/1 (*)
- put/1 (*)
- nl/0
- tab/1 (* these predicates can take a parameter that is a
- full arithmetical expression)
-
- is_endfile/1 (specifies end-of-file character)
- is_newline/1 (specifies end-of-line character)
- is_newpage/1 (specifies end-of-page character)
- is_endline/1 (detects end-of-line - must be called with its
- argument fully instantiated!)
-
- open/4 (management of input/output streams)
- open/3
- open_null_stream/1
- close/1
- current_stream/3
- stream_property/2
- nofileerrors/0
- fileerrors/0
- flush_output/1
- set_input/1
- set_output/1
- current_input/1
- current_output/1
- absolute_file_name/2
-
- read/2 (input/output of terms to arbitrary streams)
- write/2
- writeq/2
- display/2
- write_canonical/2 (a.k.a. displayq/2)
- print/2
-
- get0/2 (input/output of characters to arbitrary streams)
- get/2
- skip/2 (*)
- put/2 (*)
- nl/1
- tab/2 (* see above)
-
- character_count/2 (inquiry about streams' status)
- line_count/2
- line_position/2
- stream_position/2
- set_stream_position/2
- stream_position/3
-
- see/1 (Prolog-10 compatible file handling)
- seeing/1
- seen/0
- tell/1
- telling/1
- told/0
-
- ttyget0/1 (Prolog-10 compatible terminal input/output)
- ttyget/1
- ttyskip/1
- ttyput/1
- ttynl/0
- ttytab/1
-
- op/3 (define or delete operators)
- current_op/3 (inquire current operators)
-
- sread/2 (read a term with its symbol table)
- sread/3 (the same, using an arbitrary input stream)
-
- An (input or output) stream is a special object that can be created
- using a call like
-
- open(+FileName, +Mode, -Stream)
- or open(+FileName, +Mode, -Stream, +Options).
-
- `FileName' is the name of a file, `Mode' must be one of the atoms
- 'read', 'write' or 'append'. `Options' if given must be a list of
- options from the following set, indicating that some defaults should
- be changed:
-
- type(Type) The type of the data contained in the stream:
- either 'text' (Atari text format), 'utf' (text
- that can contain non-Atari characters), or
- 'binary' (raw bytes).
- alias(Alias) An alias name for the stream (`Alias' must be
- an atom).
- eof_action(Action) What to do if an attempt is made to read past
- the end of a file; either 'error' (cause an
- error to occur), 'eof_code' (return the EOF
- indicator) or 'reset' (start over).
- reposition Present for compatibility only - in Prolog-68,
- all files opened by the user can be positioned.
-
- The stream returned by open/[3,4] can be used with e.g.
-
- write(+Stream, ?Term)
-
- and closed with
-
- close(+Stream).
-
- Besides file streams there are certain predefined streams, accessible
- through the following names:
-
- user (for compatibility)
- user_input
- user_output
- user_error
-
- - Arithmetic
-
- 'is'/2 (evaluate expressions)
-
- '=:='/2 (compare expressions)
- '=\='/2
- '<'/2
- '=<'/2
- '>'/2
- '>='/2
-
- - Term classification:
-
- var/1
- nonvar/1
- atom/1
- integer/1
- atomic/1
-
- nonatomic/1 (negation of atomic/1)
- composite/1 (composite term?)
- simple/1 (negation of composite/1)
- callable/1 (can term be called?)
-
- - Structure access:
-
- functor/3
- arg/3
- '=..'/2
-
- name/2 (conversion between constants and strings)
- atom_chars/2
- number_chars/2
-
- numbervars/3 (enumerate variables in a term, e.g., for write/1)
-
- - Comparison of arbitrary terms:
-
- '=='/2
- '\=='/2
- '@<'/2
- '@=<'/2
- '@>'/2
- '@>='/2
- compare/3
- sort/2
- msort/2
- keysort/2
-
- When comparing terms with '@<', ..., '@>=', the following total
- ordering relation over the set of all terms is used:
-
- a) Variables @< Numbers @< Atoms @< Composite Terms
-
- b) Variable1 @< Variable2 is uniquely defined, but has no further
- meaning to the user
-
- c) Number1 @< Number2 iff Number1 < Number2
-
- d) Atom1 @< Atom2 iff Atom1's name is lexicographically less
- than Atom2's name
-
- e) Term1 @< Term2 iff i) Term1's arity is less than Term2's
- arity
-
- ii) both arities are equal and
- functor(Term1) @< functor(Term2)
-
- iii) both arities and both functors are
- equal and there exists an i
- such that for all j, 1 ≤ j < i:
-
- argument(Term1, j) == argument(Term2, j)
-
- and
-
- argument(Term1, i) @< argument(Term2, i)
-
- compare/3 acts as if it were defined as
-
- compare('<', X, Y) :- X @< Y.
- compare('=', X, Y) :- X == Y.
- compare('>', X, Y) :- X @> Y.
-
- sort/2, msort/2 and keysort/2 sort lists according to the ordering
- relation explained above. sort/2 discards duplicate elements, msort/2
- doesn't; keysort/2 expects a list of terms having the form
-
- Key - Value
-
- It ignores the 'Values' and uses the 'Keys' to sort the list.
- keysort/2 keeps duplicate elements and preserves their original
- ordering; for example,
-
- | ?- keysort([4-a, 1-b, 5-c, 1-d, 4-e, 0-f], Sorted).
- Sorted = [0-f, 1-b, 1-d, 4-a, 4-e, 5-c]
-
- These predicates are at best linear, in the worst case they are
- O(NlogN) (so we can safely conclude that they DON'T use 'quicksort').
-
- - Program loading:
-
- compile/1 (all predicates not declared dynamic are compiled)
- consult/1 (just load, do not compile any predicates)
- reconsult/1 (same as consult/1, present for compatibility)
-
- The following ISO-style directives are recognized (others will be
- implemented in future versions):
-
- :-dynamic ... (declare a predicate to be dynamic)
- :-discontiguous ... (not needed in Prolog-68)
- :-include ... (include a file)
-
- - Program status:
-
- listing/0 (list all dynamic predicates)
- listing/1 (list some dynamic predicates)
-
- current_atom/1 (inquire known atoms etc.)
- current_predicate/2
- predicate_property/2
-
- halt/0 (halt the program)
- halt/1 (ditto, specifying the exit code)
- break (start a new run level)
- abort (abort and return to Prolog top level)
-
- - Debugger:
-
- trace/0 (start debugger in creep mode)
- debug/0 (start debugger in leap mode)
- nodebug/0 (stop debugger)
-
- spy/1 (set & delete spy (=break) points)
- nospy/1
- leash/1
- harness/1
- debugging/1
- unknown/2 (trap calls to undefined predicates)
-
- unknown(-OldAction, +NewAction) is an abbreviation for
- prolog_flag(unknown, -OldAction, +NewAction) (which see).
-
- For more detailed informations concerning debugging, consult any
- decent Prolog textbook.
-
- - Database operations:
-
- abolish/1 (completely delete predicates)
- abolish/2
- asserta/1 (add clauses to a dynamic predicate)
- assertz/1
- assert/1 (= asserta/1)
- retract/1 (delete clauses of a dynamic predicate)
- retractall/1
- clause/2 (access clauses of a dynamic predicate)
-
- - Database references:
-
- Database references allow faster access to stored clauses, terms etc.
-
- asserta/2 (as above, also returning a database reference)
- assertz/2
- assert/2
- clause/3
-
- instance/2 (given a reference, retrieve a clause or term)
- erase/1 (given a reference, delete a clause or term)
-
- - Internal database:
-
- The internal database exists for reasons of efficiency. It can only
- be used for storing terms, not for storing clauses.
-
- recorda/3
- recordz/3
- recorded/3
- current_key/2
-
- Using recorda(+Key, +Term, -Ref) resp. recordz(+Key, +Term, -Ref),
- the `Term' is stored in the internal database under `Key'. A database
- reference to the stored term is returned in `Ref'; it can be used to
- remove the term via erase/1. recorded(+Key, ?Term, ?Ref) retrieves a
- stored term, current_key(?KeyName, ?KeyTerm) inquires all known keys.
-
- - Set operations:
-
- setof/3 and bagof/3 have not been implemented yet.
-
- findall/3 (find all solutions of a goal)
-
- The difference between findall/3 and bagof/3 is the treatment of free
- variables in the goal passed as parameter. bagof/3 collects all
- solutions that yield the same values for these variables, while
- findall/3 regards all free variables as existentially quantified.
-
- - Grammar rules:
-
- expand_term/2 (Called before a clause is compiled; does
- transformation of grammar rules. The user can
- define the predicate term_expansion/2 to make
- additional transformations.)
-
- phrase/3 (application of a grammar rule)
- phrase/2
-
- phrase/[2,3] can handle an entire phrase (right-hand side of a
- grammar rule). phrase/2 is defined as
-
- phrase(Phrase, List) :- phrase(Phrase, List, []).
-
- - Miscellaneous:
-
- '='/2 (unification)
-
- length/2 (list operations)
- member/2
- memberchk/2
- append/3
-
- prolog_flag/3 (inquire/modify global flags)
- prolog_flag/2
- prompt/2 (inquire/modify console input prompt)
- statistics/0 (print statistics)
- statistics/2 (inquire statistics)
-
- garbage_collect/0 (force garbage collection)
- system/1 (pass an atom to a shell, e.g., Guläm)
-
- prolog_flag/2 and prolog_flag/3 access some global flags which are
- used to control several internal features. Contrary to other Prolog
- systems, the value of a flag is always an integer (but this may change
- in future versions). The currently existing flags are:
-
- Name Values (Default) Purpose
-
- character_escapes 0, 1 (0) Controls evaluation of escape
- sequences on input and output
- fileerrors 0, 1 (1) Controls error handling when
- accessing nonexistent files
- gc_trace 0, 1, 2 (0) Controls amount of tracing
- information printed when the
- garbage collector is run
- (0=none, 1=terse, 2=verbose)
- unknown 0, 1 (1) Controls handling of undefined
- predicates (0=just fail,
- 1=signal an error)
- error_handling 0, 1, 2 (2) Controls error handling
- (0=failure, 1=activation of
- error handling routine,
- 2=additional error messages)
-
- prolog_flag(+Flag, -OldValue, +NewValue) can be used to change the
- value of the `Flag', prolog_flag(?Flag, ?Value) inquires such a value
- without changing it.
-
- The first parameter to statistics/2 must be one of the following
- keywords:
-
- 'runtime' inquire the running time
-
- 'memory' inquire the sizes of various memory areas
- 'core' (some are duplicates, e.g., heap = program)
- 'program'
- 'heap'
- 'global_stack'
- 'local_stack'
- 'trail'
-
- 'garbage_collection' garbage collection statistics (what else?)
-
- The second parameter is unified with a list of integers indicating the
- results of the inquiry.
-
- I know that this list is no sufficient documentation, but unfortunately I
- can't supply more at this time. At least I'm working on a manual written in
- LaTeX.
-
- ------- Miscellany ------------------------------------------------------------
-
- Addresses:
-
- German Federal Snail: Jens Kilian
- Holunderstraße 19
- D-71083 Herrenberg
- Germany
-
- Internet: jensk@hpbbn.bbn.hp.com
- MausNet: Jens Kilian @ BB
-
-
- There are unreasonable people out there, so I must specifically disclaim any
- warranty even for this pre-release version:
-
- NO WARRANTY
-
- - BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
- OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
- PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
- OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
- TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
- PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
- REPAIR OR CORRECTION.
-
- - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
- WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
- INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
- OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
- TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
- YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGES.
-
-
- My employers haven't even heard of Prolog-68, so don't waste effort on them.
-
- -------------------------------------------------------------------------------
-
- Have fun,
-
- Jens Kilian
-